home *** CD-ROM | disk | FTP | other *** search
/ CD Ware Multimedia 1994 November / Cd Ware (Nro. 2) - Epimundo.iso / DOS / PG / DIRECT.ZIP / COMMENT.DOC < prev    next >
Encoding:
Text File  |  1994-06-04  |  7.6 KB  |  67 lines
  1. COMMENT.DOC    4 June 1994
  2.             Adrian Urquhart 100126, 1211
  3.  
  4.     This Édocumentation Éaccompanies Éthe ÉDIRECTRY.C Éand ÉDIRECTRY.H 
  5. èsource files. As is usual, the source Écode Éis provided on an "as is" 
  6. èbasis, and I will Énot Ébe Éheld Éresponsible Éfor any damage, however 
  7. ècaused, incurred as a result of the use of this code.
  8.  
  9.     This source Éfile Éprovides Éthree Éfunctions Éwhich Écan Ébe used 
  10. èdirectly within your own Éprograms. ÉYou'll Éneed ÉMicrosoft C version 
  11. è6.00 or higher to compile the Écode, Ébut ÉI've included a small model 
  12. èobject file as well. If Éthere Éis Ésufficient interest I will produce 
  13. èobject files for other memory models.
  14.  
  15.                             FUNCTION USAGE
  16.  
  17. int SearchDisk (const char * Target)
  18.  
  19.     This routine uses recursion Éto Ésearch Éthe current directory and 
  20. èall sub-directories for the Éfile Éspecified Éin Target. Target should 
  21. èeither  a unique file name e.g. ÉFRED.DOC. ÉIf Éyou want to be able to 
  22. èuse wild cards, you will need to modify the code. The search will stop 
  23. èat the first occurrence of the ÉTarget Éfile name. It's easy enough to 
  24. èadd code to carry on with the search. ÉThe function returns a 1 if the 
  25. èsearch was successful, otherwise a 0.
  26.  
  27. Int EmptyDirectory (void)
  28.  
  29.     This routine should carry a Government Health Warning. Starting at 
  30. èthe current directory, it uses recursion Éto empty this directory plus 
  31. èall Ésub-directories, Éremoving ÉÉeach ÉÉsub-directory ÉÉas Éit Égoes. 
  32. èTherefore, if you call it at Éthe Éroot Édirectory of a disk, you will 
  33. èend up with an Éempty Édisk. ÉThe Éonly Éexception Éto Éthis Éis if it 
  34. èencounters a read-only file, in Éwhich Écase Éthe routine ends. Hidden 
  35. èfiles and system files are removed. ÉThe Éfunction Éreturns a 1 if all 
  36. èdirectories could be emptied, otherwise a 0.
  37.  
  38. Int CreateDirectory (char * NewPath)
  39.  
  40.     This function overcomes the Élimitation Éof Éthe mkdir() function, 
  41. èwhich can only create one Édirectory Élevel Éat Éa time. The parameter 
  42. èNewPathName should include a drive specification, Éand must end with a 
  43. èbackslash i.e. d:\level1\level2\level3\finalone\. It doesn't matter of 
  44. èsome or all of the directory path already exists. The function returns 
  45. èa 1 if the new directory was created, otherwise a 0.
  46.  
  47.                          FUNCTION DESCRIPTION
  48.  
  49. SearchDisk
  50.  
  51.     This function uses a structure of type find_t, which is defined in 
  52. èdos.h. The structure has the following members:
  53.  
  54. struct find_t
  55. {
  56.     char reserved [21] ;    /* Used by DOS                */
  57.     char attrib ;            /* Attribute byte of file    */
  58.     unsigned wr_time ;        /* Time of last file update    */
  59.     unsigned wr_date ;        /* Date of last file update    */
  60.     long size ;            /* Length of file, in bytes    */
  61.     char name [13] ;        /* Null-terminated file name    */
  62. } ;
  63.  
  64.     Firstly, a Écall Éto É_dos_findfirst() Éis Émade, Égiving Éa "*.*" 
  65. èfilespec as the file name to search for. Only normal and sub-directory 
  66. èfiles will be found. The address Éof Éthe find_t structure is given as 
  67. èthe third parameter. If a 0 is Éreturned, Éthen a file has been found, 
  68. èand its details will be in the find_t structure.
  69.  
  70.     We now find out if it's a sub-directory which has been located. If 
  71. èit is, we make sure it's Énot Éthe Éaliases Éfor the current or parent 
  72. èdirectories (i.e. "." and ".."). ÉIf Énot, Éwe change directory to the 
  73. èfound directory, and call SearchDisk again.
  74.  
  75.     If it wasn't a Ésub-directory, Éwe Écompare Éthe Éfile name to the 
  76. èTarget name. If there is an exact match, Éwe return with a 1. If there 
  77. èis no match, we now Éenter Éa Éloop, calling _dos_findnext() to locate 
  78. èthe next file in the directory Éuntil Éthere are no more files. Again, 
  79. èwe check to see if the current Éfile Éis a sub-directory, and if it is 
  80. èwe change directory to it, Éand Écall ÉSearchDisk. ÉIf it's not a sub-
  81. èdirectory we compare the file name Éto Éthe ÉTarget, and if there is a 
  82. èmatch we return with a 1.
  83.  
  84.     If we have called ÉSearchDisk Éfrom Éwithin Éitself and it returns 
  85. èwith a 0, then we move back Éup Éto Éthe parent directory and carry on 
  86. èwith the search. If a É1 Éis Éreturned, Éwe Éknow Éthat the search was 
  87. èsuccessful, so the function returns. ÉUsing Éthe stricmp() function to 
  88. ècompare the current file with the Étarget Éfile means that the case of 
  89. èthe Target is unimportant.
  90.  
  91. EmptyDirectory
  92.  
  93.     This function works in much Éthe Ésame Éway as SearchDisk. It uses 
  94. èthe same find_t Éstructure Éand É_dos_findfirst() Écall Éto locate the 
  95. èfirst file in the current Édirectory. ÉThis Étime, however, we specify 
  96. èthat normal, hidden, system, and Ésub-directory files should be found. 
  97. èThereafter, operation is the same as Éfor SearchDisk, except that each 
  98. èfile is deleted Éas Éit Éis Éfound, Éusing Éthe Éremove() function. If 
  99. èEmptyDirectory has been called from within Éitself and it returns with 
  100. èa 1, then that means that Éthe Écurrent directory has been emptied, so 
  101. èwe move back up to the Éparent directory and remove the sub-directory. 
  102. èIf a 0 Éis Éreturned, Éthat Égenerally Émeans Éthat Éthe sub-directory 
  103. ècontains a read-only Éfile, Éwhich Écan't Ébe Éerased. ÉIn Éthis case, 
  104. èEmptyDirectory returns to its caller with a 0 value.
  105.  
  106.     You could modify the code Éso Éthat Éeven Éif a read-only file was 
  107. èencountered, its attribute Écould Ébe Échanged Éand Éthen Éit could be 
  108. èdeleted.
  109.  
  110. CreateDirectory
  111.  
  112.     This Éroutine Éalso Éuses Éa Ésupport Éroutine, ÉExtractDirectory. 
  113. èFirstly, the     NewPath parameter is broken into Éits component parts by 
  114. èthe _splitpath() function. After the Écall, the local variables drive, 
  115. èdir, filename, and ext will hold Éthe drive, directory path name, file 
  116. èname, and file extension, respectively. In our case, the file name and 
  117. èextension are not required.
  118.  
  119.     We then attempt to change the Écurrent Édrive to the one specified 
  120. èin the NewPath argument. If not successful, Éwe return with a 0 value. 
  121. èOtherwise, we move to the root directory of the drive.
  122.  
  123.     Next, we repeatedly Éextract Éeach Édirectory Éname Éfrom Éthe dir 
  124. èvariable, and then try to change directory to it. If we can't, we call 
  125. èmkdir() Éto Écreate Éit, Éand ÉÉthen ÉÉretry Échanging Édirectory. ÉIf 
  126. èsuccessful, we carry on, otherwise we return with a 0 value.
  127.  
  128.     To extract each directory, the local variable path is first set to 
  129. èpoint to the second character of Éthe Édir Évariable. This will be the 
  130. èfirst letter of the directory, after Éthe Éinitial É'\'. A call to the 
  131. èExtractDirectory routine is made, Égiving Épath Éas an argument, along 
  132. èwith the NextDirectory variable, which upon Éreturn will hold the name 
  133. èof the next directory. ÉUpon Éreturn Éfrom ExtractDirectory, path will 
  134. èpoint to the starting position within Éthe dir variable from where the 
  135. ènext directory name is to be extracted.
  136.  
  137.     Within ExtractDirectory, for as long Éas Éparameter É1 points to a 
  138. ènon-zero character which is Énot Éa Ébackslash Éthen that character is 
  139. ècopied to the Ébuffer Épointed Éto Ébe Éparameter É2. ÉParameter É1 is 
  140. èincremented, and the Ébuffer Éindex É(local Évariable Éx) incremented. 
  141. èNext, a 0 is Éappended Éto Éthe Énew Édirectory Éname Éwhich is now in 
  142. èparameter 2. If x is 0, that Émeans that there were no more characters 
  143. èto be extracted from parameter É1, Éso Éa ÉNULL is returned, otherwise 
  144. èparameter 1 is returned.
  145.  
  146.                    -------------------------------
  147.  
  148.     Plainly, there is plenty of scope for adding improvements to these 
  149. èfunctions. CreateDirectory could check Éfor Éillegal Édrives or names, 
  150. èfor example.
  151.